プロジェクトドキュメント構築向け静的サイトジェネレータ『MkDocs』及び『Material for MkDocs』の個人的導入＆設定まとめ
直近携わっているプロダクトで「ユーザーガイド」的なドキュメントを作る機会があり、暫く前に幾つか見繕ってみた結果「MkDocs」というツールを選定して環境を作成＆整備して来ました。個人的にこのツールは使い勝手がとても良いと思っており、継続して使って来ていました。
当エントリでは今後の備忘録としてMkDocsの基本的な導入・設定方法と、そのMkDocsで適用させたスタイル「Material for MkDocs」をここまで使ってきた中での個人的Tipsなどをまとめておきたいと思います。
目次
MkDocsとは
MkDocsは、プロジェクトドキュメントの構築に向けた、高速でシンプルかつリッチな静的サイトジェネレーターです。ドキュメントのソースファイルはMarkdownで記述することが出来、単一のYAML構成ファイルで構成されます。
その他特徴としては以下があります。
- GitHubページ、Amazon S3、または他の任意の場所でホストできる完全に静的なHTMLサイトを構築可能
- 見栄え(テーマ)を簡単に切り替え可能
- ドキュメントを書きながらプレビューが可能(変更を保存するたびに、ブラウザが自動的に再読み込みされて更新される)
- テーマやプラグインをインストールすることでプロジェクトをカスタマイズ可能
MkDocsのインストール
現行最新のMkdocsはPython3系で稼働します。導入対象の環境(MacOSX)は初期設定でPython2系が入っていたのでまずはこの環境を切り替えたいと思います。
MacOSXのバージョンは以下。
% sw_vers ProductName: Mac OS X ProductVersion: 10.15.3 BuildVersion: 19D76
現行Python導入バージョンの確認：
% python --version Python 2.7.16
pyenvの導入
手っ取り早い切り替え方法としてpyenvを導入し、Python3系の環境を別途用意して行きます。brewを利用可能な状態にセットアップしておき、brewコマンドでpyenvをインストール。各種PATH指定に関しても指定の内容で済ませておきます。pyenv --versionコマンドで所定のバージョンが表示されればOKです。
% brew install pyenv % echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bash_profile % echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bash_profile % echo 'eval "$(pyenv init -)"' >> ~/.bash_profile % source ~/.bash_profile % pyenv --version pyenv 1.2.20
Python3.8系の最新バージョンを導入します。導入可能なバージョンの一覧を確認し、
% pyenv install --list | grep "3.8" 3.8.0 3.8-dev 3.8.1 3.8.2 3.8.3 3.8.4 3.8.5 miniconda-3.8.3 miniconda3-3.8.3
インストール実行。対象バージョンが導入されたことを確認します。
% pyenv install 3.8.5 % pyenv global 3.8.5 % pyenv rehash % pyenv versions system * 3.8.5 (set by /Users/xxxxxxx/.pyenv/version) % python --version Python 3.8.5
Mkdocsのインストール
Mkdocsのインストールはpipを使って行います。
% pip --version pip 20.1.1 from /Users/xxxxxxx/.pyenv/versions/3.8.5/lib/python3.8/site-packages/pip (python 3.8)
pip install mkdocsでインストール実施。mkdocs --versionコマンドでバージョン情報が表示されればインストール完了です。
% pip install mkdocs % mkdocs --version mkdocs, version 1.1.2 from /Users/xxxxxxx/.pyenv/versions/3.8.5/lib/python3.8/site-packages/mkdocs (Python 3.8)
基本操作
プロジェクト新規作成：mkdocs new (プロジェクト名)。
% mkdocs new devio-test INFO - Creating project directory: devio-test INFO - Writing config file: devio-test/mkdocs.yml INFO - Writing initial docs: devio-test/docs/index.md
ドキュメントサーバの起動：mkdocs serve。停止はcommand+Cで行けます
% mkdocs serve INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 0.12 seconds [I 200724 08:37:15 server:296] Serving on http://127.0.0.1:8000 INFO - Serving on http://127.0.0.1:8000 [I 200724 08:37:15 handlers:62] Start watching changes INFO - Start watching changes [I 200724 08:37:15 handlers:64] Start detecting changes INFO - Start detecting changes
サーバ起動後、http://localhost:8000/にアクセスする事によって生成内容を確認出来ます。
デプロイ用コンテンツの作成：mkdocs build。「site」ディレクトリと共に配下に静的コンテンツが諸々作成されます。出来上がったコンテンツを任意のWebサーバ等にデプロイすれば出来上がり。--cleanオプションを付けて実行することで「site」配下の古いファイルを削除した上で作成が行えます。
% mkdocs build --clean INFO - Cleaning site directory INFO - Building documentation to directory: /Users/xxxxxxx/Desktop/project/devio-test/site INFO - Documentation built in 0.08 seconds
ページはMarkdownファイル(*.md)として作成し、Markdown形式またはHTML形式での記載内容を認識・表示します。
% vi docs/index.md
# Welcome to MkDocs
For full documentation visit [mkdocs.org](https://www.mkdocs.org).
## Commands
* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.
## Project layout
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
## クラスメソッド
こんにちは！こんばんわ！
- [コーポレートサイト](https://classmethod.jp)
- <a target="_blank" href="https://dev.classmethod.jp/">クラスメソッド発「やってみた」系技術メディア | Developers.IO</a>
サーバを起動させたまま編集・保存を行うことも可能なので、保存後にリアルタイムで編集内容が反映されて確認もズムーズに行えます。
各種設定・定義について
MkDocsでは、諸々の設定は全てmkdocs.ymlという設定ファイルに書き入れていくことで対応します。プロジェクト作成直後の設定ファイルの中身は以下のような非常にシンプルな内容となっています。ここに、(個人的に必要と思った)設定を追加していきながらその内容について解説していきます。
% vi mkdocs.yml site_name: My Docs
サイト名の変更・ベースドキュメントフォルダの指定
site_nameではドキュメントサイトの名称を指定可能です。また、docs_dirで任意のドキュメントルートフォルダを指定することも可能です。(初期設定はdocs)
site_name: Developers.IO ブログ用MkDocs docs_dir: 'docs'
Copyrightの指定
copyrightでは著作権情報に関する記載を指定可能です。
# Copyright copyright: 'Copyright © 2010 - 2020 - Classmethod, Inc.'
テーマに関する設定
themeではMkDocsの表示スタイルに関する設定を行えます。直近使ってた設定ファイルは以下のようなものでした。
theme:
name: material
language: ja
icon:
logo: material/school
repo: fontawesome/brands/git-alt
favicon: favicon.png
# タブ表示を有効.
features:
- tabs
個別テーマの導入と適用
MkDocsでは、MkDocs本体とは別に個別テーマの導入を行うことで、表示スタイルの変更を行うことが可能です。
個人的は下記の「Material for MkDocs」が好きで良く使っています。
ライブラリをpipコマンドでインストールし、
% pip install mkdocs-material
theme配下にてnameで対象テーマの指定を行うことで適用されます。
theme:
name: material
スタイル適用後の画面です。ガラリと雰囲気変わりましたね。
言語指定
検索インデックスを構築するときに使用する言語を指定。
language: ja
アイコン指定
サイト名と併せて表示されているアイコン画像を個別に指定可能です。
icon:
logo: material/school
repo: fontawesome/brands/git-alt
Favicon指定
任意の画像を用意し、faviconでその画像を指定することでfaviconとして表示させることが出来ます。(docsをルートとするパス指定)
favicon: favicon.ico
タブ形式のメニュー表示
theme配下に以下の形で設定を追記することで、メニュー構成を「タブ配置を踏まえた」形に変更することが出来ます(後述するnavの1階層目をタブで切り替えできるようにするオプション)。
features:
tabs: true
上記設定を踏まえて、ページ構成を以下のような形で記載します。navは構成上最上位に来る要素です。インデントを経て次の階層(1階層目)の部分が、メニュー上でタブ表記される形になります。
# Navigation
nav:
- はじめに: index.md
- クラスメソッドについて:
- クラスメソッドとは: classmethod.md
- CLPについて:
- CLPとは: clp.md
設定に沿う様にファイルも新しく作成。
% touch docs/classmethod.md % touch docs/clp.md
以下の様に表示が変わったことが確認出来ました。ページ数自体がそもそも多くなるような場合であれば、この構成を取ることでよりスッキリした形で情報を整えられるかと思います。
ページの作成・構成・相対パス
基本的なファイル構造に関する内容の詳細は以下。任意のフォルダ構造を持った形を取ることが出来、ページの指定もそこからフォルダを踏まえた記載の形式を取ることでリンクされるようになります。
nav:
- はじめに: index.md
- クラスメソッドについて:
- クラスメソッドとは: classmethod.md
- メニュー:
- サービス: menu/services.md
- 事例: menu/usecases.md
- セミナー・相談会: menu/seminar.md
上記ファイル構造を踏まえた形でフォルダ及びファイルを配置。
% pwd /Users/xxxxxx/xxxxxx/xxxxxx/devio-test % mkdir docs/menu/ % touch docs/menu/services.md % touch docs/menu/usecases.md % touch docs/menu/seminar.md
Markdownファイルの内容を以下のような形式で書くことで、
# クラスメソッド - [サービス](menu/services.md) - [事例](menu/usecases.md) - [セミナー・相談会](menu/seminar.md)
以下のような形でコンテンツを表示・リンクさせることが可能です。
本文内容の記述
MkDocsはmdファイル内にMarkdown形式、及びHTML形式で内容を記述することが可能です。混在も可能。
画像の表示
前述のフォルダ、ファイル構成と同様に、当該ページから参照可能なパス形式で画像ファイルを指定することで表示が可能です。(※下記ページ「Linking to images and media」から抜粋)
Cupcake indexer is a snazzy new project for indexing small cakes.  *Above: Cupcake indexer in progress*
カスタムCSSの設定
extra_cssで別途ファイルを指定することで任意のCSSスタイル定義を適用させることが可能です。
extra_css:
- css/custom.css
必要な構成を準備し、
% mkdir docs/css % touch docs/css/custom.css
CSS設定ファイルに内容を追記。
/** ヘッダーカラーを緑色に. */
.md-header {
background-color: #006633;
color: #fff;
}
.md-tabs__inner {
background-color: #006633;
}
nav.md-tabs {
background-color: #006633;
}
.md-tabs--active {
color:#ffffff !important;
}
個別のCSS設定を効かせることが出来ました。
日本語検索対応
MkDocsではドキュメント内の検索も行えます。公式ドキュメントでは幾つか検索有効化のための設定が紹介されていたのですが、
- Material for MkDocs を日本語対応した話＆初めてのOSSコントリビュート - miyalog
- Setting up site search - Material for MkDocs
直近試した感じだと、ここまでの設定に新たに何かを加える事無く、検索出来ているようでした(language: ja で表示言語を日本語にしたくらい)。 もうちょっと複雑な設定だと追加で何か必要になるのかな？この辺は別途稿を改めて深堀り出来ればと思います。
その他Markdown拡張
その他、個人的に良さそうだなと思って追加した設定は主に以下の内容。
markdown_extensions:
- admonition
- codehilite:
linenums: true
guess_lang: false
use_pygments: false
noclasses: true
- toc:
permalink: true
- fontawesome_markdown
- admonition:
- 注意書きや警告など、ユーザーの目を引く様なテキスト表示を行う時に使える装飾。
- Admonitions - Material for MkDocs
- codehilite
- コードブロックに関する表記設定。
- Code blocks - Material for MkDocs
- toc
- 見出しに関する設定。ここでは見出し末尾にアンカーリンクを表示させています。
- Setting up navigation - Material for MkDocs
- fontawesome_markdown
- Webアイコンフォントの表示。
mkdocs.yml設定サンプル
このエントリで紹介した「MkDocsで出来ること」はほんの一部であり、他にも色々な機能や設定・カスタマイズが可能です。関連ドキュメントを参考に色々深堀りしてみて頂ければと思います。
site_name: Developers.IO ブログ用MkDocs
docs_dir: 'docs'
theme:
name: material # MkDocs for Materialに表示スタイルを切替.
language: ja # メニュー言語を日本語に変更.
icon: # サイト名横のアイコン画像を変更.
logo: material/school
repo: fontawesome/brands/git-alt
favicon: images/favicon.png # ファビコン画像の設定.
features:
- tabs # タブ表示を有効化.
# Navigation
nav:
- はじめに: index.md
- クラスメソッドについて:
- クラスメソッドとは: classmethod.md
- メニュー:
- サービス: menu/services.md
- 事例: menu/usecases.md
- セミナー・相談会: menu/seminar.md
- CLPについて:
- CLPとは: clp.md
markdown_extensions:
- admonition
- codehilite:
linenums: true
guess_lang: false
use_pygments: false
noclasses: true
- toc:
permalink: true
- fontawesome_markdown
extra_css:
# ユーザー個別で効かせたい設定を記述.
- css/custom.css
# fontawesome_markdownで使える設定を別途追加.
- "https://maxcdn.bootstrapcdn.com/font-awesome/4.6.1/css/font-awesome.min.css"
# Copyright
copyright: 'Copyright © 2010 - 2020 - Classmethod, Inc.'
気になったことなど
国際化対応は？
- Support i18n · Issue #211 · mkdocs/mkdocs · GitHub
- Internationalization · Issue #945 · mkdocs/mkdocs · GitHub
関連してそうなトピックを参照する限り、MkDocsでは国際化(i18n)対応に関する公式的な仕組みは現状提供されていない模様。惜しい。
まとめ
という訳で、静的サイトジェネレータツール、「MkDocs」の紹介でした。
比較的簡単且つスムーズに「良い感じのドキュメント体制」を準備出来るのはMkDocsの良いところだなーと個人的には思っています。ただ1点「多言語対応」が為されていないのが気になるところではありました。この辺りが必要になってくるケースになるのであれば、MkDocs以外のツールを選ばざるを得ないところなのかな...と思っております。MkDocsは引き続き活用しつつ、「多言語対応」の機能も踏まえたツールやサービスを幾つか試してみたいと思います。
